home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / Translation.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-12  |  12.0 KB  |  326 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        Translation.h
  3.  
  4.      Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5.  
  6.      Version:    Technology:    Macintosh Easy Open 1.1
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    © 1991-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __TRANSLATION__
  19. #define __TRANSLATION__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __FILES__
  25. #include <Files.h>
  26. #endif
  27. #ifndef __COMPONENTS__
  28. #include <Components.h>
  29. #endif
  30. #ifndef __TRANSLATIONEXTENSIONS__
  31. #include <TranslationExtensions.h>
  32. #endif
  33.  
  34.  
  35.  
  36. #if PRAGMA_ONCE
  37. #pragma once
  38. #endif
  39.  
  40. #ifdef __cplusplus
  41. extern "C" {
  42. #endif
  43.  
  44. #if PRAGMA_IMPORT
  45. #pragma import on
  46. #endif
  47.  
  48. #if PRAGMA_STRUCT_ALIGN
  49.     #pragma options align=mac68k
  50. #elif PRAGMA_STRUCT_PACKPUSH
  51.     #pragma pack(push, 2)
  52. #elif PRAGMA_STRUCT_PACK
  53.     #pragma pack(2)
  54. #endif
  55.  
  56. /* enumerated types on how a document can be opened*/
  57. typedef short                             DocOpenMethod;
  58.  
  59. enum {
  60.     domCannot                    = 0,
  61.     domNative                    = 1,
  62.     domTranslateFirst            = 2,
  63.     domWildcard                    = 3
  64. };
  65.  
  66. /* 0L terminated array of OSTypes, or FileTypes*/
  67. typedef OSType                             TypesBlock[64];
  68. typedef OSType *                        TypesBlockPtr;
  69. /* Progress dialog resource ID*/
  70.  
  71. enum {
  72.     kTranslationScrapProgressDialogID = -16555
  73. };
  74.  
  75. /* block of data that describes how to translate*/
  76. struct FileTranslationSpec {
  77.     OSType                             componentSignature;
  78.     const void *                    translationSystemInfo;
  79.     FileTypeSpec                     src;
  80.     FileTypeSpec                     dst;
  81. };
  82. typedef struct FileTranslationSpec FileTranslationSpec;
  83.  
  84. typedef FileTranslationSpec *            FileTranslationSpecArrayPtr;
  85. /*****************************************************************************************
  86. * 
  87. *   GetFileTypesThatAppCanNativelyOpen
  88. * 
  89. *  This routine returns a list of all FileTypes that an application can open by itself
  90. * 
  91. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  92. *             appSignature        signature (creator) of application
  93. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  94. * 
  95. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  96. */
  97. EXTERN_API( OSErr )
  98. GetFileTypesThatAppCanNativelyOpen (short                 appVRefNumHint,
  99.                                  OSType                 appSignature,
  100.                                  FileType *                nativeTypes)                        TWOWORDINLINE(0x701C, 0xABFC);
  101.  
  102. /*****************************************************************************************
  103. * 
  104. *  ExtendFileTypeList
  105. * 
  106. *  This routine makes a new list of file types that can be translated into a type in the given list
  107. *  Used by StandardFile
  108. * 
  109. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  110. *             numberOriginalTypes        number of file types in orgTypeList
  111. *              extendedTypeList        pointer to a buffer to be filled with file types
  112. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  113. * 
  114. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  115. *             numberExtendedTypes        number of file types put in extendedTypeList
  116. */
  117. EXTERN_API( OSErr )
  118. ExtendFileTypeList                (const FileType *        originalTypeList,
  119.                                  short                     numberOriginalTypes,
  120.                                  FileType *                extendedTypeList,
  121.                                  short *                numberExtendedTypes)                TWOWORDINLINE(0x7009, 0xABFC);
  122.  
  123.  
  124. /*****************************************************************************************
  125. * 
  126. * 
  127. *  This routine checks if a file can be opened by a particular application.
  128. *  If so, it returns if it needs to be translated first, and if so then how.
  129. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  130. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  131. * 
  132. *  Enter:    targetDocument        document to check if it can be opened
  133. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  134. *             appSignature        signature (creator) of application to open doc
  135. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  136. *             onlyNative            whether to consider if document can be translated before opening
  137. *             howToOpen            pointer to buffer in which to put how the document can be opened
  138. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  139. * 
  140. *  Exit:    howToOpen            whether file needs to be translated to be read
  141. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  142. *             returns                noErr, noPrefAppErr
  143. */
  144. EXTERN_API( OSErr )
  145. CanDocBeOpened                    (const FSSpec *            targetDocument,
  146.                                  short                     appVRefNumHint,
  147.                                  OSType                 appSignature,
  148.                                  const FileType *        nativeTypes,
  149.                                  Boolean                 onlyNative,
  150.                                  DocOpenMethod *        howToOpen,
  151.                                  FileTranslationSpec *    howToTranslate)                        TWOWORDINLINE(0x701E, 0xABFC);
  152.  
  153.  
  154. /*****************************************************************************************
  155. * 
  156. *  GetFileTranslationPaths
  157. * 
  158. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  159. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  160. * 
  161. *  Enter:    srcDoc            source file or NULL for all matches
  162. *             dstDoc            destination FileType or NULL for all matches
  163. *             maxResultCount
  164. *             resultBuffer
  165. *  Exit:    number of paths
  166. */
  167. EXTERN_API( short )
  168. GetFileTranslationPaths            (FSSpec *                srcDocument,
  169.                                  FileType                 dstDocType,
  170.                                  unsigned short         maxResultCount,
  171.                                  FileTranslationSpecArrayPtr  resultBuffer)                    TWOWORDINLINE(0x7038, 0xABFC);
  172.  
  173. /*****************************************************************************************
  174. * 
  175. *  GetPathFromTranslationDialog
  176. * 
  177. *  This routine, with a given document, application, and a passed typelist will display the
  178. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  179. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  180. *  The routine returns the translation path information.
  181. * 
  182. *  Enter:    theDocument            FSSpec to document to open
  183. *             theApplication        FSSpec to application to open document
  184. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  185. *                                 you would like the documented translated to.  Order most perferred
  186. *                                 to least.
  187. * 
  188. *  Exit:    howToOpen            Translation method needed to open document
  189. *             howToTranslate        Translation specification
  190. *             returns                Any errors that might occur.
  191. */
  192. EXTERN_API( OSErr )
  193. GetPathFromTranslationDialog    (const FSSpec *            theDocument,
  194.                                  const FSSpec *            theApplication,
  195.                                  TypesBlockPtr             typeList,
  196.                                  DocOpenMethod *        howToOpen,
  197.                                  FileTranslationSpec *    howToTranslate)                        TWOWORDINLINE(0x7037, 0xABFC);
  198.  
  199.  
  200. /*****************************************************************************************
  201. * 
  202. *   TranslateFile
  203. * 
  204. *  This routine reads a file of one format and writes it to another file in another format. 
  205. *  The information on how to translated is generated by the routine CanDocBeOpened.
  206. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  207. *  The destination file must not exist.  It is created by this routine.  
  208. * 
  209. *  Enter:    sourceDocument            input file to translate
  210. *             destinationDocument        output file of translation
  211. *             howToTranslate            pointer to info on how to translate
  212. *  Exit:    returns                    noErr, badTranslationSpecErr 
  213. */
  214. EXTERN_API( OSErr )
  215. TranslateFile                    (const FSSpec *            sourceDocument,
  216.                                  const FSSpec *            destinationDocument,
  217.                                  const FileTranslationSpec * howToTranslate)                TWOWORDINLINE(0x700C, 0xABFC);
  218.  
  219. /*****************************************************************************************
  220. * 
  221. *   GetDocumentKindString
  222. * 
  223. *  This routine returns the string the Finder should show for the "kind" of a document
  224. *  in the GetInfo window and in the kind column of a list view.  
  225. * 
  226. *  Enter:    docVRefNum        The volume containing the document
  227. *             docType            The catInfo.fdType of the document
  228. *             docCreator        The catInfo.fdCreator of the document
  229. *             kindString        pointer to where to return the string
  230. * 
  231. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  232. *             returns            noErr, or afpItemNoFound if kind could not be determined
  233. */
  234. EXTERN_API( OSErr )
  235. GetDocumentKindString            (short                     docVRefNum,
  236.                                  OSType                 docType,
  237.                                  OSType                 docCreator,
  238.                                  Str63                     kindString)                            TWOWORDINLINE(0x7016, 0xABFC);
  239.  
  240. /*****************************************************************************************
  241. * 
  242. *  GetTranslationExtensionName
  243. * 
  244. *  This routine returns the translation system name from a specified TranslationSpec
  245. * 
  246. *  Enter:    translationMethod    The translation path to get the translation name from
  247. * 
  248. *  Exit:    extensionName        The name of the translation system
  249. *             returns                Any errors that might occur
  250. */
  251. EXTERN_API( OSErr )
  252. GetTranslationExtensionName        (const FileTranslationSpec * translationMethod,
  253.                                  Str31                     extensionName)                        TWOWORDINLINE(0x7036, 0xABFC);
  254.  
  255.  
  256. /*****************************************************************************************
  257. * 
  258. *  GetScrapDataProcPtr
  259. * 
  260. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  261. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  262. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  263. *  with a list all the formats that you have available to be translated, and the length of each.
  264. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  265. *  the formats that 'fmts' list said was available.
  266. * 
  267. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  268. *             dataH                    Handle in which to put the requested data
  269. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  270. *             
  271. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  272. */
  273. typedef CALLBACK_API( OSErr , GetScrapDataProcPtr )(ScrapType requestedFormat, Handle dataH, void *srcDataGetterRefCon);
  274. typedef STACK_UPP_TYPE(GetScrapDataProcPtr)                     GetScrapDataUPP;
  275. enum { uppGetScrapDataProcInfo = 0x00000FE0 };                     /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes) */
  276. #define NewGetScrapDataProc(userRoutine)                         (GetScrapDataUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppGetScrapDataProcInfo, GetCurrentArchitecture())
  277. #define CallGetScrapDataProc(userRoutine, requestedFormat, dataH, srcDataGetterRefCon)  CALL_THREE_PARAMETER_UPP((userRoutine), uppGetScrapDataProcInfo, (requestedFormat), (dataH), (srcDataGetterRefCon))
  278. typedef GetScrapDataUPP                 GetScrapData;
  279. /*****************************************************************************************
  280. * 
  281. *  TranslateScrap
  282. * 
  283. *  This routine resizes the destination handle and fills it with data of the requested format.
  284. *  The data is generated by translated one or more source formats of data supplied by
  285. *  the procedure srcDataGetter.  
  286. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  287. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  288. * 
  289. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  290. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  291. *             destinationFormat            Format of data desired
  292. *             destinationData                Handle in which to store translated data
  293. *             
  294. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  295. */
  296. EXTERN_API( OSErr )
  297. TranslateScrap                    (GetScrapData             sourceDataGetter,
  298.                                  void *                    sourceDataGetterRefCon,
  299.                                  ScrapType                 destinationFormat,
  300.                                  Handle                 destinationData,
  301.                                  short                     progressDialogID)                    TWOWORDINLINE(0x700E, 0xABFC);
  302.  
  303.  
  304.  
  305.  
  306. #if PRAGMA_STRUCT_ALIGN
  307.     #pragma options align=reset
  308. #elif PRAGMA_STRUCT_PACKPUSH
  309.     #pragma pack(pop)
  310. #elif PRAGMA_STRUCT_PACK
  311.     #pragma pack()
  312. #endif
  313.  
  314. #ifdef PRAGMA_IMPORT_OFF
  315. #pragma import off
  316. #elif PRAGMA_IMPORT
  317. #pragma import reset
  318. #endif
  319.  
  320. #ifdef __cplusplus
  321. }
  322. #endif
  323.  
  324. #endif /* __TRANSLATION__ */
  325.  
  326.